


Champ is designed to run on the 
Commodore 64, BBC Micro model B, and 
Sinclair Spectrum 48K. 

lt comprises an assembler for 
6502/6510 or Z80 assembly language, a 
program editor, and a monitor/debugger/ 
disassembler. These facilities make Champ 
a powerful aid to the assembly language 
programmer. 


LOADING CHAMP 


BBC Model B — CHAIN “” 
C64 — Hold down [SHIFT] and 
hit [RUN/STOP] 

Spectrum 48K — LOAD “” 


Champ will auto-run when loading is complete, so, 
having issued the LOAD command, you need do 
nothing until the screen clears and displays the 
copyright message. Stop the tape, remove it, and 
replace it with a blank data tape if you intend to save 
program files from Champ. 

In addition to the copyright message on the screen, 
you will see a message about Champ’s location in 
memory; this is important data, so make a note of it 
all now, even if you’re not sure what it’s for. When 
you've done that, hit [ESC] to run Champ. (This refers 
to the BBC Micro; the corresponding key presses for 
the Commodore 64 and Spectrum are listed in the 
Key Conventions panel.) 

The screen should look like this: 








Label Instruction Operand 
Field Field Field 


Edit Line } 


Error Line} | 
Command Line ASSEMBLES 





At this point, the computer is waiting for you to type 
in an assembly language program, but don’t do 
anything yet. 

Have a look at the two example programs given 





overleaf, and choose the one for your computer. (The 
6502 program for the BBC and Commodore 64 
machines, the Z80 for the Spectrum). The two 
programs are equivalent. 

The first thing to notice is that there are a lot of 
semi-colons (;) about. These may look strange, but 
are simply the equivalent of REM in BASIC. In 
machine code programming lines beginning with ‘:’ 
are known as COMMENTS, and they are extremely 
important if you want to understand something you 
may have written weeks ago. You can put anything 
you like inside a comment without affecting the 
program. The comment must begin on a new line. We 
have put the equivalent BASIC program lines in 
comments so that you can see how the machine code 
instructions can be made to operate in the same way 
as BASIC. 
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Spectrum, 1 


SS Re aa ne aa 


65026510 ASSEMBLER-EDITOR 
MON I TOR/DEBUGGER-DISASSEMBLER 


DEVELOPED FOR THE 
HOME COMPUTER ADVANCED COURSE 


PERSONAL SOF TUARE SERVICES 
WRITTEN BY TONY STOOOART 

TO COLD START USE CALL 4096 
TO WARM START USE CALL 4099 


AMS ASSEMBLED WIT iT 
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BBC Micro, 2 


Commod p 64, 3 








Opening display 1,2,3 

The opening display of Champ 
shows the warm start and cold start 
addresses of the Champ program. If 
you quit to BASIC and want to return 
to Champ you should use PRINT USR 
(addr), SYS (addr) or CALL (addr), 
where addr is the appropriate warm or 
cold start address. (A cold start is 
what you get after switching your 
machine off; it clears Champ’s 
buffers of any source code you have 
entered. A warm start restarts Champ 
as it was when you quit it.) 





Any line that does not start with a ‘’ is an 
assembly language statement. The first one is ORG 
$CQQ0. This is not a machine code instruction: it 
tells the assembler where to put your program when it 
turns your assembly language into machine code. 
ORG is short for ORIGIN; $CQQO is a hexadecimal 
numeral (signified by the ‘$’ sign), equivalent to 
49,152 decimal. In BASIC, you don’t need to worry 
about where your program is because the interpreter 
looks after all that for you. Now, you have the whole 
of the computer under your control, and that means 
that you decide where you want your program to go. 

You also have to tell the assembler where to put 
your variables. Once again, BASIC does all this for 
you, but in machine code you have to do it yourself. 
For large machine code programs it is usually a good 
idea to put all your variables together in one block, 
but for small programs it’s all right to put them next to 
the appropriate part of the program for clarity. The 
next few assembly language statements in our 
example tell the assembler that you want to use two 
variables, | and J, and that they will be found at the 


beginning of the program, right after the ORIGIN 


address. Because we are not going to use numbers 
larger than 255, we need only one byte for each of the 
two variables, so the DB (Define Byte) statement is 
used. If we had wanted to use larger numbers we 
could have used the DW (Define Word) command to 
reserve two bytes for each variable. BASIC would 
automatically have used up five bytes for each 
variable. These storage-defining commands simply 
tell the assembler not to use an area of memory 
because you're going to store some variables there. 
They also tell the assembler how big each area is and 
what the areas are going to be called (in this case | 
and J). 

The storage commands, the ORG command and 
the COMMENT are all called pseudo-ops (‘ops’ being 
Short for ‘operations’) because the assembler doesn't 
generate any machine code from them; they are just 
there for your (and the assembler’s) attention. 

All the other assembly language statements will be 
translated by the assembler into executable machine 
code instructions — that is, instruction codes that 
will cause the microprocessor to do something. 
Among these instructions are: Load A Register; Test 





a Flag; and Jump or Branch to a new address. These 
make up the rest of the example program listing. 

If you're not too clear about any of the three types 
Of pseudo-ops (COMMENT, ORG or storage) then 
please re-read this section. It’s not at all difficult, 
once you get the hang of it, but do take it at your own 
pace. 

Now that we have covered the different types of 
statement understood by the assembler, you can 
enter the example program. Please refer to the 
relevant Hands On section below. 


Operating Modes 

<ASSEMBLE> mode 
is used after you have typed in an assembly 
language program, in order to assemble it into 
machine code 

<INSERT> mode 
is what you use to type in an assembly 
language program 

<EDIT> mode 
enables you to modify an existing assembly 
language program 

<DEBUG> mode 
allows the inspection or modification of the 
contents of the memory, or the execution of a 
machine code program 


Both <ASSEMBLE> and <DEBUG> modes are 
command modes. In these modes various keys 
represent commands that make something happen 
to your program or to memory. On the other hand, 
<INSERT> and <EDIT> are text modes; with these 
you Can move program text around on the screen, and 
add to, or modify, it. 

You can change from one mode to another as shown 
here. 





<n ee |) INSERT 
[ESC] 


KEY 
CONVENTIONS 


A letter (or letters) enclosed in 
Square brackets, thus [Al], 
means ‘the key carrying this 
symbol’. Special keys referred to 
in this Manual are: 


KEY MEANING 

[RET | [Return key |; 
[Enter] on 
Spectrum 

[ESC] [Escape key]: 
[<] on C64; 
[Caps Shift + 1] on 
Spectrum 

[CRSRR] [Cursor Right]: 
[Caps Shift + 
8] on Spectrum 
[Cursor Left]; 
(Caps Shift + 
5] on Spectrum 
[Cursor Up]: 
[Caps Shift + 
7] on Spectrum 
[Cursor Down]; 
[Caps Shift + 
6] on Spectrum 
[Control Key]: 
(Caps Shift] on 
Spectrum 
[Space Bar] 








Hands on — Spectrum 

The <ASSEMBLE> prompt on the bottom line of the 
screen display is telling you that the assembler is 
waiting for you to do something. We want to enter our 
first program, so tell Champ you want to EDIT by 
pressing CAPS SHIFT and 1 simultaneously. The 
prompt changes to <EDIT> and shows a flashing 
underscore at the cursor position. The first thing you 
need to put in is a comment to say what the program 
does, so type a semi-colon, together with the title of 
the program and any other information you think might 
be useful. Press ENTER before you reach the 
right-hand side of the screen. The line you have just 
typed will move up one place and the cursor will start 
flashing at the beginning of the new line. The prompt 


2 


will now show <INSERT>, because you are now 
inserting new information into the assembler. If you 
make a mistake before pressing ENTER, then use the 
Cursor keys (which operate as normal) to correct your 
mistake, and just type over any mis-spelt words. If 
you pressed ENTER before noticing your error, don't 
worry; you Can Correct it in a minute. 

As you can see, you can also use blank comment 
lines to space your program listing out to make it 
more readable. 

When you have finished typing the introductory 
comment, and the cursor is at the beginning of a new 
line, try pressing ENTER once more. You will find that 
you go back to <EDIT> mode. In <EDIT> mode, you 
can use the cursor keys to scroll the listing up and 


CHAMP EXAMPLE PROGRAM 
6902 VERSION | 
ORG $C000 
VARIABLES > 
| DB 
J DB SQ 
PROGRAM 
; 10 FOR | = 100 TO 1 STEP-1 
LDX #964 
NEXTI SIX | 
; 20 FOR J = 255 TO 1 STEP-1 
LDX #$FF 
NEXTJ SIX J 
; 30 NEXT J 
LDX J 
DEX 
BNE NEXTJ 
; 40 NEXT | 
LDX | 
DEX 
BNE NEXTI 
; 0 RETURN: REM TO BASIC OR CHAMP 
RTS 


down and move the cursor through any line you may 
want to change. Correct any mistakes you may have 
made (but don’t press ENTER) and move the cursor 
back down to the bottom of the text. Now press 
ENTER again and you should once more have the 
cursor on a blank line with text above it and nothing 
below. If not, use ENTER to toggle between <EDIT> 
and <INSERT>, and use the cursor keys to get you 
to the correct position at the bottom of the text. 

If you now type a space without a semi-colon, the 
cursor will skip to the second coloured field (column), 
because Champ ‘knows’ that if you type a space 
here, you don’t want anything in the first field. Now 
type in ORG followed by a space. Once again, when 
Champ gets. the space, it knows that it has to skip to 
the next field. So you can complete the ORG 
instruction by typing $CQGO followed by ENTER. All 
instructions except comments are typed into the 
assembler in this way; when you've finished using a 
particular field (or don’t want to use it at all), use the 
space bar to move to the next field or ENTER to move 
to the next line. 

If you want to type a line containing a label, then 
Start in the LABEL field (the leftmost one), type your 
label followed by a space, and continue with 
instruction and operand fields. 

some typing errors will be recognised by Champ 
when you press ENTER and will cause an error 
message to be displayed. Possible errors at this point 
are LABEL, INSTRUCTION or OPERAND errors. 
These correspond respectively to the three coloured 
fields in the assembler display, so if you get an error 
message you should find your mistake in the field 
referred to. Use the cursor keys to go back and 
correct the mistake when you’ve found it. 





When you've typed the listing in, press ENTER one 
last time to return to <EDIT> mode, then use the 
cursor keys to run through the listing to ensure that it 
looks like the example. When you are satisfied, press 
CAPS SHIFT and 1 to return to <ASSEMBLE> mode 
and SAVE your text, using the S command. (This can 
be loaded back at any time using the J command.) 
This is a good habit, as it is easy to lose what you are 
doing when using machine code since you can't use 
SHIFT/BREAK to stop a runaway program. 

Having SAVEd your listing, you can now 
assemble it. Type A (for assemble), and Champ will 
display ASSEMBLE=> on the prompt line. Type in 3 
as your assembly option — this tells the assembler 
what sort of listing you want and is explained more 
fully elsewhere in the manual. Press ENTER at this 
point and assembly should commence. 

lf all is well, Champ will print a version of your 
listing with some extra numbers on the left-hand side. 
The leftmost column of numbers shows the 
addresses to which each instruction has been 
assembled. They may look a little odd because they 
are expressed in hexadecimal notation. Notice that 
the addresses do not increase after comment lines: 
this is because comments do not produce any 
machine code. This is reflected in the second two 
columns of numbers, which contain the machine code 
values loaded into memory. You can see that 
comment lines once again produce no machine code. 

After the listing you will also see a tabie of all the 
labels you used: this is called the symbol table and 
Champ produces it for your convenience. It enables 
you to find the parts of the program you want quickly. 

Note that addresses of variables and jump labels 
are held in the symbol table in the same way; this is 
because the microprocessor holds them in a similar 
way in its internal registers. 

Having successfully assembled our example 
program, we want to examine the program as it is in 
memory. Enter the monitor part of Champ by pressing 
M. The screen should now display the <DEBUG> 
prompt. | 

The start address of your program is not $COQQ, 
but $CQ@@2, because of the space that you reserved 
for two variables. So type Q (for disassemble), 
followed by CQ@@2 (you don't need a $ sign in 
<DEBUG> mode). 

When you press ENTER, you will see a listing 
Similar to the code you entered, but without the 
comments, variables, labels and pseudo-ops. You will 
remember that these produce no machine code. (If 
you now press any key, the Disassemble feature will 


display a further block of memory; it will do this 


repeatedly, until you press CAPS SHIFT/1. To return 
to the disassembly, you will then need to type 
QC002.) 

lf this listing doesn’t look like the machine code 
you typed into the assembler, then type CAPS 
SHIFT/1, return to <ASSEMBLE> mode by typing A 
ENTER and reassemble the prograra, checking that 
you use the correct option and that when you finish 
the assembler says that it found no errors. 

And now for the moment of truth! If the listing 
printed by the disassemble command looks correct, 











In<EDIT> mode, source text is 
displayed with the cursor on the 
Edit Line, and <EDIT> on the 
Command Line. Text on the Edit 
Line can be overwritten or deleted 
(using [DEL] or [SP]). [RET] 
causes the Edit Line contents to 
be checked for syntax and format. 
An error message will appear if 
the line is faulty, and the text will 
remain on the Edit Line. If the line 
is acceptable, it will be entered 
into the source text, and mode 
will change from <EDIT> to 
<INSERT>. [RET] toggles these 
two modes, while [ESC] toggles 
<EDIT> and <ASSEMBLE> 
modes. 

The following keys can be 
used to move the source text on 
the screen, assuming the text on 
the Edit Line is correct. Ifa line is 
edited, and if the edited text is 
valid, then any of the following 
keys has the effect of entering the 
new line into the source text 
without changing the mode. 





Itis in this mode that you actually 
type your Assembly language 
program into the Assembler. The 


Command Line Shows 
<INSERT>, and a_ flashing 
cursor appears on the Edit Line. 
The Edit Line (and the whole 
screen) is divided into three 
coloured columns, corresponding 
to the Label, Instruction, and 
Operand Fields of an Assembly 
language program: 


Label Field 

A label is any alphanumeric 
string of up to six characters. 
There must be a letter in the first 
position of the Field. A label does 
not require a colon (or any other 
character) as delimiter. 


Instruction Field 

Instructions are Assembly 
language mnemonics as in MOS 
Tech 6502 and Zilog Z80 
Specifications. They may be two, 
three, or four letters long, starting 
in the first position of the Field. 


Operand Field 
Operands may be hex constants 
(which must be preceded by $), 
labels, symbols, or expressions 
comprising two operands 
Separated by + or — Decimal, 
octal, and binary constants are 





<EDIT> MODE 
COMMANDS 


<INSERT> MODE 
COMMANDS 








KEY EFFECT 

IN Moves one line up 
the text. 

IW] Moves one line 


down the text. 

[CTRL|+[U] Moves the screen 
text up one page. 

[CTRL]+[D] Moves the screen 
text down one 
page. 

(CTRL]+[T] Moves to the top 
of source text. 

[CTRL]+[B] Moves to the 
bottom of source 
text. 

(CTRL]+[Z] Deletes the Edit 
Line contents. 

[ESC] Enters 
<ASSEMBLE> 
mode. 

[RET] Enters 
<INSERT> 
mode. 


N.B. The text movement keys 
have the same effects when used 
in <ASSEMBLE> mode, but 
they then donot require[CTRL] to 
be pressed. Thus [U] in 
<ASSEMBLE> mode moves 
the screen text up one page. 





not permitted. Operand formats 
for the various addressing modes 
are as specified by MOS Tech 
and Zilog. 


Text entry in <INSERT> is 
subject to Field Formatting: This 
means it is impossible for you to 
type aseven-character label, or a 
five-character instruction. Typing 
an extra character, or hitting 
[SPACE], causes the cursor to 
skip to the first position of the 
next Field. 

The [CRSRR], [CRSRL], and 
[DEL] keys act as normal in 


<INSERT> mode — subject to 


Field Formatting — but the 
delete key acts on the cursor 
character rather than on the 
character to the left of the 
cursor. 

When you hit [RET] in 
<INSERT> mode, the contents 
of the Edit Line are checked for 
syntax and format; if an error is 
found, then a message appears 
on the Error Line. If no error is 
found, then the contents of the 
Edit Line enter the source: text, 
and the Edit Line is cleared for the 
entry of a new line. Hitting [RET] 
when the Edit Line is blank 
toggles between <EDIT> mode 
and <INSERT> mode. 





<DEBUG> MODE 
COMMANDS 


This mode combines the 

following functions: ABBREVIATIONS 

Memory Monitor — allows you to addr any hex address 
inspect and alter the contents of —saddr start address of a 
memory. block of memory 

Hex Disassembler — allows you — faddr finish address of a 

to interpret the contents of block of memory 
memory as machine code to be (=1+ address of last 
converted back into Assembly byte of block) 


language. daddr destination address in 
Debugger— allows you [0 hex 

execute machine code programs hx a hex value (hx<= 
and trap errors. FF) 


CPU register name 
Jhepues macommandie U register 


see below 
but the Command Line/Edit Line/ expr ae as Fe 
Field Format display of the other expression in one or 
modes is not used: the screenis a two operands; 


blank page showing only the 
prompt and a cursor. In this mode 
all constants are hex constants 
without the ‘$’ prefix, although 
the ‘H’ command = supports 
decimal constants. 


operands may be 
decimal constants, ‘$’ 
— prefixed hex 
constants, or legal 
symbols; operators 
are ‘+’ or ‘— 

bystr a string of hex byte 
values separated by 
Spaces 

chstr a String of characters 
(exactly as it appears, 


no separators) 

COMMAND’ EFFECT 

@ addr Memory from the given address onwards is displayed 
one byte at a time, in hex and ASCII equivalent. Hit 
[RET] to advance to next byte, hit [ESC] to return to 
command level, or type a hex constant to replace the 
existing content of the byte 

A Return to <ASSEMBLE> mode 

D addr Memory from the given address onwards is displayed in 
screen pages; hit any key to continue, or [ESC] to 
return to command level 

F saddr Every byte between saddr and faddr is filled with hx 

faddr hx 

M daddr The block of memory between saddr and faddr is 

saddrfaddr copied to the block starting at daddr 

Q addr Memory from addr onwards is disassembled; hit [RET] 
to continue, and [ESC] to return to command level 

G addr The code starting at addr is executed (returnable) 

C addr Execute from addr (non-returnable) 

Bn=addr A breakpoint number n, (between 1 and'8) is set at 
addr, to cause a break in execution of any program 
which accesses the contents of addr as an instruction; 
press [C] [RET] to continue from breakpoint 

En Eliminates breakpoint n 

T Displays the addresses of all the breakpoints 

Rregname Displays the contents of a CPU register and accepts a 


new value (similar to the function of ‘@’ above) 

J addr Executes the code from addr onwards, one instruction 
at a time, giving a full register display. Hit [J] to 
continue, [ESC] to return to the command level 

H expr Displays the decimal, hex, and binary value of expr 

§ bystr Searches the memory from $0000 onwards for every 
occurrence of bystr. The word ‘searching’ is displayed 
while the program is searching, and the address is 
displayed when bystr is found. Hit [RET] to continue 

5 the search, or [ESC] to return to command level 

Nchstr As‘S’ above 

W Load, Save, and Verify machine code to tape; see 

BASIC panel 








CPU Register Na 
Abbreviations 

























































6502 
= Accumulator; X, Y= X,Y A = Ac 
registers; P= Statusregister,SP Status 1 
= Stack Pointer H. 
Pointer: | 


<ASSEMBLE 


COMMAND 
FORMATS 


Find => string [RET] KEY PR 
Searches the Assembly language [F] Fir 
program from the start of the 
program for the first occurrence [L] Lo 
of the given string. 

Next => string [RET] [W] Se 
Searches the Assembly language 

program for the next occurrence {[V] Ve 
of the given string. The search 

begins from the end of the [P] Pr 
program line currently on the Edit 


Line. [Q]} Qu 
Find =>[RET] and [M] 
Next => [RET] 


As above, but this searches for 
the string defined in last‘F or‘N’ [ESC] 
command. While a search is 
preceeding, the message 


‘searching appears onthe Error [A] As 
Line. If the search is successful, = 
the line containing the string 

being searched for appears on To abort 
the Edit Line. If the search is donotel 
unsuccessful, the last line of the just hit! 
program appears on the Edit Line. prompt 


Load => Save => Verify => 
These must all be followed by a 
filename; double quotes are not KEY 
needed, but the filename must be (J) 
legal for the users machine. (S] 
Print => expression [RET] 
This prints the hex value of the FRI 
given expression on the Error 
Line. eg. 

Print =>$F8-S$C1 $37 

Symbols already defined in 
source text can be used in 
expressions; but only one 
Operator (+ or —) is allowed per 
expression. 

Quit =>[Y] 

This quits Champ and returns — 
control to the BASIC system only 
if [Y | follows the prompt; 

any other response aborts the 
command. 

[M] 

Enter <DEBUG> mode. Return | 
from there to <ASSEMBLE> 


eens 


mode by pressing [A] [RET]. 
[ESC] 
Toggle <EDIT> and 


<ASSEMBLE> modes. 

Assemble => (option number) [RET] 
This assembles the source text in 
one of a variety of ways, 
depending upon which numerical 
option is chosen: 












Register Name 
bbreviations 
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= X,Y A = Accumulator, F = Flag/ 
er.SP Status register, H.L.BC,D.E = 


MBLE 


guage 
Mf the 
rence 


guage 
rence 
earch 
f the 
e Edit 


es for 
or‘N’ 
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ssage 
Error 
SSful, 
String 
rs on 
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]. 
and 


[RET] 
textin 
ways, 
erical 





H...E registers; SP = Stack 
Pointer; IX, lY = IX, lY registers. 








6502 


INSTRUCTION 
#304 


$A290 
$31 FE,X 
$7B,X 
($2A,X) 
($2A),Y 


ADDRESSING MODE 
Immediate 

$3C Zero Page (Direct) 
Absolute (Direct) 
Absolute Indexed 
Zero Page Indexed 
Pre-Indexed (Indirect) CCF 
Post-Indexed (Indirect) 


INSTRUCTION 
FORMATS 


Implied 


ASSEMBLY LANGUAGE 
FORMATS 


KEY PROMPT FUNCTION 
[F} Find=> _ Finda string 
[N} Next=> _ Find a string PSEUDO- 
[L] Load=> Load a source op- 
file CODES MEANING 
[W] Save=> Savea 
source file ORG origin: 
= gin: assemble 
IV] Verify=> Verify a. addr == machine code in 
source file memory from addr 
[P] Print=> Print value of onwards. The program 
; EXPression line with ORG on it 
a Quit => ra to BASIC cannot take a label. 
nter ; 
equate: set the symbol 
<DEBUG> in the Label Field equal 
mode to the constant, 
[ESC] Enter symbol, or expression 
Ae as in the Operand Field. 
define byte(s): load 
[A} Assemble Assemble this location, and as 
> program 


To abort any of these commands, 
do not enter a command operand, 
just hit [RET] in response to the 
prompt. 


many following as 
required, with the 
value(s) of const or 
chrstr 

define word: load this 
location with the lo- 


inti byte, and the next 
Spectrum variations location with the hi- 
KEY PROMPT byte of the operand 
[J] Load => define storage: add the 
(S] Save=>: value of the operand to 


[sym.shift] + Verify => 
[RI 


OPTION NUMBER 


the location address of ~ 


this instruction 


ASSEMBLY 
OPTIONS 


E.g. Assemble 


Abbreviations: 


addr  a$-prefixed hex address 

const a$-prefixed hex 
constant; as an operand 
of DB, const must be a 
Single-byte value. A 
String of constants, such 
as (DB const [SP] const 
[SP] const... etc) is 
valid 
a String of characters 
enclosed in single quotes 
(e.g. ‘AB3%9K10’) 
any valid symbolic 
operand 


=>2_ [RET] 


INSTRUCTION 


AS9F 
($ED46),A 
A,(HL) 
A,(IY +d) 





01234567 
Display full 
listonscreen NY NY NY NY 
Load m/code 
into memory 
Copy screen 
to printer 
Verify labels, 
symbols & 
syntax 
Display 
symbol table 
on screen 


NNYYNNYY 


NNNNYYYY 


Teer Ty) TF 


EELS YF 


Y= This facility enabled 
N = This facility disabled 


causes the source text to be 
assembled with error-checking, 
and theresulting machine code to 
be loaded into memory as directed 
by the ORG pseudo-op-code. The 
symbol table is displayed on the 
Screen, but no assembly listing 
appears on the screen, and there 
is no output to the printer. 

Any option number can be 
preceded by 1, which gives a 
double-line display if the screen 
list facility is enabled. 

If an error is found during 
assembly, a message will appear 
on the Error Line, assembly will 
cease, and the screen will display 
the source text with the faulty 
instruction appearing on the Edit 
Line. 





280 

ADDRESSING MODE 
Register (Direct) 
Immediate 
Absolute (Direct) 
Register (Indirect) 
Indexed (Indirect) 
Implied 


LINKING MACHINE 
CODE AND BASIC 


Once you're familiar with both 
Champ and Assembly language 
programming, you'll probably 
want to be able to call special- 
purpose machine-code routines 
from BASIC programs, rather than 
write entire programs in machine 
code. The easiest way of doing 
this is: 

1) Using Champ, develop the 
Assembly language routine until 
it works. 

2) From<ASSEMBLE> mode, 
SAVE the Assembly language 
routine to tape for future 
reference. 

3) Assemble the routine into 
memory, choosing an ORG 
address near the top of User RAM 
(See your computer User Manual 
for Memory Map and advice). 

4) From <DEBUG> mode, 
SAVE the block of memory 
containing your machine code to 
tape. 

5) Quit Champ. 


6) Write your BASIC program, 
Starting with the instructions 
necessary to set the Top of User 
RAM pointers to an address 
Safely below the ORG address of 





your routine. Follow those 
instructions in the program witha 
LOAD instruction that will load 
your machine code routine from 
tape to the location from which it 
was SAVEd (consult your User 
Manual). 

7) Whenever you need to execute 
the machine-code routine in the 
BASIC program, use aCALL, SYS, 
or USR instruction with your 
routine’s ORG address. 

8) Save the BASIC program as 
usual. 


lf you exit from Champ to BASIC, 
and type LIST, you should see an 
example of this technique at 
work: When you LOAD Champ, 
you load only the short BASIC 
loader program which you see; 


when this is executed, it LOADS - 


Champ itself as a machine code 
file into memory, then calls it as a 
machine code routine. 





CHAMP ERROR 
MESSAGES 


Error messages appear on the 
Error Line in all modes except 
<DEBUG>, which _ prints 
‘ERROR’ at the current cursor 
position. 



















MEANING 
A syntax or 
format error in 
the Label Field. 
A syntax or 
format error in 
the Instruction 
Field. 

A syntax or 
format error in 
the Operand 
Field. 

The Label or 
Symbol 
displayed on 
the Edit Line 
has not been 
assigned an 
address or a - 
value. 

The relative 
jump in the 
instruction on 
the Edit Line 
requires a 
displacement of 
more than 127 
bytes forward 
or 128 bytes 
backward. 
Assembling the 
instruction on 
the Edit Line 
into memory 
would overwrite 
CHAMP itself, 
or some 
protected 
memory, or 
would be out of 
range. 

The operand of 
a <DEBUG> 
command 
contains illegal 
symbols, or is 
too large a 
quantity, or is a 
bad address, 
etc. 


MESSAGE 
LABEL ERROR 







INSTRUCTION 
ERROR 








OPERAND 
ERROR 








UNDEFINED 
LABEL 











JUMP OUT OF 
RANGE 













OVERFLOW 














ERROR 














you can execute it in <DEBUG> mode by typing 
GC@@2 ENTER. (In other words, G followed by the 
Starting address.) If all is well, the <DEBUG> prompt 
will return almost immediately, telling you that your 
program has been executed. 

You might like to enter and run the BASIC program 
in order to appreciate the difference in speed between 
the two languages. You could even modify the 
programs to put an extra loop around the outside of 
the two loops already present and use a stop-watch 
to calculate exactly how much faster machine code 
is. Be prepared to wait a long time for the BASIC! 


DISASSEMBLY LISTING — Z80 


co02——<(‘éKSASCté‘iUD” A$64 
C004 320000 LD ($CQOQ),A 
C007 «= SEFF_—sédLD ASFF 
co09 «= B2M1C0_-—s«LD ($C001),A 
cooc «= B8ADICD_-—Ss«LD A($C001) 
COOF =. 3D DEC A 

C010 «= «OFT ~—S sR NZ, $C009 
C12 3A00C0 LD A($CQQQ) 
C015 «=S sD DEC A 

Ch16 «= (PEC UR NZ,$C004 
cog «=—s« RET 
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Getting out of <EDIT> mode 1 
When the Edit Line is blank in 
<EDIT> mode on the Spectrum, 
ENTER should toggle <INSERT> 
mode, but may cause an error 
message. Type a semi-colon (;), thus 
turning the line into a comment. 
ENTER will then toggle <INSERT> 
mode, and you can delete the entire 
spurious line from <EDIT> or 
<ASSEMBLE> mode. 


Label error, 2 

The second occurrence of LABL1 
in this example is detected as a label 
error or erased. 


Instruction error, 3 

Champ is here being used on a 
Spectrum. However, the assembly 
language instruction ST does not 
exist in Z80 code, so an instruction 
error is flagged when the line is 
entered 


Operand error, 4 

Here Champ is being used on a 
Commodore 64. The 6502 assembly 
language instruction BNE requires an 
operand, So trying to enter the line 
without one causes an operand error. 


Assembly error, 5 


Not all errors are trapped at entry 
time. Here, the first line of code 
contains a logical error, which has 
been caught. Hitting any key will 
restore <ASSEMBLY > mode. 


Completed assembly, 6 

The assembly has been 
successful, as the message shows. 
Because the option chosen was 11, 
each line of assembly listing 
occupies two screen lines; option 1 is 
logically equivalent, but allows only 
one screen line per assembly line. 


Disassembly function, 7 


Q, the disassembly function in 
<DEBUG> mode, produces a block of 
lines of disassembly; hit ESCAPE to 
return to <DEBUG> and then hit any 
key to disassemble the next block. 


Memory display function, 8 

D, the memory display function in 
<DEBUG> mode shows the hex 
contents (and their ASCII equivalents) 
of a block of memory; hit ESCAPE or 
any key to return or continue, 
respectively. This is the Z80 display, 
which shows six bytes per line. The 
6502 display shows eight. 


Hands on — BBC Micro and Commodore 64 
The <ASSEMBLE> prompt on the bottom line of the 
screen display is telling you that the assembler is 
waiting for you to do something. We want to enter our 
first program so tell Champ you want to EDIT by 
pressing ESCAPE on the BBC Micro, or <— on the 
Commodore 64. The prompt changes to <EDIT> and 
shows a flashing square at the cursor position. The 
first thing you need to put in is a comment to say 
what the program does, so type a semi-colon together 
with the title of the program and any other information 
you think might be useful. Press RETURN before you 
reach the right-hand side of the screen. The line you 
have just typed will move up one place and the cursor 
will start flashing at the beginning of the new line. 
The prompt will now show <INSERT>, because you 
are now inserting new information into the assembler. 
If you make a mistake before pressing RETURN, then 
use the cursor keys (which operate as normal) to 
correct your mistake, and just type over any mis-spelt 
words. If you pressed RETURN before noticing your 
error, don’t worry; you Can correct it in a minute. 

As you can see, you can also use blank comment 
lines to space your program listing out to make it 
more readable. 


CHAMP EXAMPLE PROGRAM 
6502 VERSION 
ORG $C00O 
| VARIABLES 
| DBO 
J DBO 
PROGRAM 
' 1Q FOR | = 100 10 1 STEP-1 
LDX #964 
NEXT| STIX | 
0 FOR J = 255 10 1 STEP-1 
LDX  #$FF 
NEXT) SIX J 
- 30 NEXT J 
LOX J 
DEX 
BNE NEXT J 
AQ NEXT | 
LDX | 
DEX 


BNE NEXT | 
; 50 RETURN: REM TO BASIC OR CHAMP 
RTS 


When you have finished typing the introductory 
comment, and the cursor is at the beginning of a new 
line, try typing RETURN once more. You will find that 
you go back to <EDIT> mode. In <EDIT> mode, you 
can use the cursor keys to scroll the listing up and 
down and move the cursor through any line you may 
want to change. Correct any mistakes you may have 
made (but don’t press RETURN) and move the cursor 
back down to the bottom of the text. Now press 





RETURN again and you should once more have the 
cursor on a blank line with text above it and nothing 
below. If not, use RETURN to toggle between 
<EDIT> and <INSERT>, and use the cursor keys to 
get you to the correct position at the bottom of the 
text. 

If you type a space without a semi-colon, the 
cursor will skip to the second coloured field (column), 
because Champ knows that if you type a space here, 
you don’t want anything in the first field. Now type in 
ORG followed by a space. Once again, when Champ 
gets the space, it knows that it has to skip to the next 
field. So you can now complete the ORG instruction 
by typing $CQQ@ followed by RETURN. All 
instructions except comments are typed into the 
assembler in this way; when you've finished using a 
particular field (or don’t want to use it at all), use the 
space bar to move to the next field or RETURN to 
move to the next line. 

lf you want to type a line containing a label, then 
Start in the LABEL field (the leftmost one), type your 
label followed by a space, and continue with 
instruction and operand fields. 

Some typing errors will be recognised by Champ 
when you press RETURN and will cause an error 
message to be displayed. Possible errors at this point 
are LABEL, INSTRUCTION or OPERAND errors. 
These correspond respectively to the three coloured 
fields in the assembler display, so if you get an error 
message you should find your mistake in the field 
referred to in the error message. Use the cursor keys 
to go. back and correct the mistake when you've 
found it. 

When you've typed the listing in, press RETURN 
one last time to return to <EDIT> mode, then use the 
cursor keys to run through the listing to ensure that it 
looks like the example. When you are satisfied, press 
the ESCAPE key to return to <ASSEMBLE> mode 
and SAVE your text, by using the W command. (This 
can be loaded back at any time, using the L 
command.) This is a good habit, as it is easy to lose 
what you are doing when using machine code, since 
you can't use STOP or Control/C to stop a runaway 
program. : 

Having SAVEd your listing, you can now assemble 
it. Type A (for assemble), and CHAMP will display 
ASSEMBLE=> on the prompt line. Type in 3 as 
your assembly option — this tells the assembler 
what sort of listing you want and is explained more 
fully elsewhere in the manual. Press RETURN at this 
point and assembly should commence. 

If all is well, Champ will print a version of your 
listing with some extra numbers on the left-hand side. 
The leftmost column of numbers shows the 
addresses to which each instruction has been 
assembled. They may look a little odd because they 
are expressed in hexadecimal notation. Notice that 
the addresses do not increase after comment lines: 
this is because comments do not produce any 
machine code. This is reflected in the second two 
columns of numbers, which contain the machine code 
values loaded into memory. You can see that 
comment lines once again produce no machine code. 

After the listing you will also see a table of all the 








labels you used: this is called the symbol table and 
_ Champ produces it for your convenience. It enables 
you to find the parts of the program you want quickly. 

Note that addresses of variables and jump labels 
are held in the symbol table in the same way; this is 
because the microprocessor holds them in a similar 
way in its internal registers. | 

Having successfully assembled our example 
program, we want to examine the program as it is in 
memory. Enter the monitor part of Champ by pressing 
M and RETURN. The screen should now display the 
DEBUG prompt. 

The start address of your program is not $CQ@Q, 
but $C@2, because of the space that you reserved 
for two variables. So type Q (for disassemble), 
followed by CQ@2 (you don't need a $ sign in 
<DEBUG> mode). 

When you press RETURN, you will see a listing 
similar to the code you entered, but without the 
comments, variables, labels and pseudo-ops. You will 
remember that these produce no machine code. (If 
you now press any key, the Disassemble feature will 
display a further block of memory; it will do this 
repeatedly, until you press ESCAPE (BBC) or <— 
(C64). To return to the disassembly you will then 
need to type QCVA2.) 

lf this listing doesn’t look like the machine code 
you typed into the assembler then press ESCAPE, 
return to <ASSEMBLE> mode by typing A RETURN 
-and reassemble the program, checking that you use 





Points to remember 
LABELS must start with a letter, and must not be 
more than six alphanumeric characters long. 

INSTRUCTION MNEMONICS must be standard 
6902 or Z80: two, three, or four letters long. 

OPERANDS must follow standard 6502 or Z80 
formats. They can contain arithmetic expressions 
comprising symbols or hex constants and a ‘+’ or 
‘—’ operator, and can fill, but not exceed, the entire 
operand field. 

In <EDIT> mode you can change the text on 
the Edit Line, and you can move the entire text file up 
and down on the screen using the following keys (on 
the Spectrum, replace the control key by CAPS 
~ SHIFT). 


KEY EFFECT 

[T] Moves the Edit Line up one line 

[Ll] Moves the Edit Line down one 
line 

[(CTRL]+[T] Moves to the top of the text 

[CTRL]+[B] Moves to the bottom of the text 

[CTRLJ+[U] Moves text up one screen page 

[CTRL|+[D] Moves text down one screen 
page 

(CTRL]+[Z] Deletes the contents of the Edit 
Line 





DISASSEMBLY LISTING — 6502 


C002 A264 LDX #964 
C004 BEQOCB = STX SCO 
CQQ7 A2FF LDX #OFF 
C009 BEQICB = = STX $CO01 
CORC AE@1C@  LDX $0001 
COOF CA DEX 


C010 DOF9 BNE $0009 
C012 AE@@C@ LDX $C000 
CQ15 CA DEX 
C16 DOEE BNE $0004 
C018 60 RTS 


the correct option and that when you finish the 
assembler says that it found no errors. 

And now for the moment of truth! If the listing 
printed by the disassemble command looks correct, 
you can execute it in <DEBUG> mode by typing 
GCQ@2 RETURN. (In other words, G followed by the 
starting address.) If all is well, the <DEBUG> prompt 
will return almost immediately, telling you that your 
program has been executed. 

You might like to enter and run the BASIC program 
in order to appreciate the difference in speed between 
the two languages. You could even modify the 
programs to put an extra loop around the outside of 
the two loops already present and use a stop-watch 
to calculate exactly how much faster machine code 
is. Be prepared to wait a long time for the BASIC! 


These keys without [CTRL] have the same effects in 
<ASSEMBLE> mode, but you cannot delete or 
otherwise modify your text in that mode. 


If your program executes successfully, then the 
<DEBUG> prompt and cursor will return to the 
screen. The ‘D’ command can now be used to display 
the contents of the memory that the program should 
affect. If the results are successful, then you might 
want to SAVE the machine code (called the object 
code to distinguish it from the assembly language 
source code) to tape, using the ‘W’ command in 
<DEBUG> mode. Having done that, you might like to 
try altering some of the object code in memory using 
the ‘@’ command, also in <DEBUG> mode. Once 


you've started to understand roughly what’s going on 


in Champ, you should simply play around with any and 
every command or option that meets your eye — you 
Cant damage anything and it’s really the only way to 
learn. . 
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